Distribution av Python-paket: Publicering på PyPI och versionshantering

Pythons omfattande ekosystem drivs av en enorm samling paket som är lättillgängliga via Python Package Index (PyPI). Denna guide ger en komplett översikt över hur du distribuerar dina egna Python-paket via PyPI för att säkerställa att de är tillgängliga för utvecklare över hela världen. Vi kommer att utforska de nödvändiga verktygen, bästa praxis för versionshantering och arbetsflöden för att skapa och publicera högkvalitativa Python-paket.

Varför ska du distribuera ditt Python-paket?

Att distribuera ditt Python-paket erbjuder många fördelar:

• Dela ditt arbete: Låter andra utvecklare enkelt återanvända din kod, vilket främjar samarbete och innovation. Föreställ dig ett globalt team som använder dina specialiserade dataanalysverktyg byggda i Python.
• Beroendehantering: Förenklar processen för att hantera beroenden i andra projekt. Ditt paket kan installeras med ett enda kommando, tillsammans med alla dess beroenden.
• Bidra till öppen källkod: Ger dig möjlighet att bidra till öppen källkod-gemenskapen och få erkännande för ditt arbete. Många kritiska mjukvarukomponenter är paket med öppen källkod som underhålls av utvecklare över hela världen.
• Versionskontroll och uppdateringar: Ger ett strukturerat sätt att hantera versioner, släppa uppdateringar och åtgärda buggfixar. Detta säkerställer att användare alltid har tillgång till den senaste och mest pålitliga versionen av ditt paket.
• Enkel installation: Förenklar installationen för användare genom `pip install ditt-paketnamn`.

Nödvändiga verktyg för distribution av Python-paket

Flera verktyg är nödvändiga för att skapa och distribuera Python-paket:

• setuptools: Ett flitigt använt bibliotek för att definiera paketmetadata, inklusive namn, version, beroenden och ingångspunkter. Det är de facto-standarden för att paketera Python-projekt.
• wheel: Ett distributionsformat som ger en effektivare och mer tillförlitlig installationsprocess jämfört med källdistributioner. Wheels är förbyggda distributioner som kan installeras utan att kräva kompilering.
• twine: Ett verktyg för att säkert ladda upp ditt paket till PyPI. Twine krypterar dina inloggningsuppgifter och paketdata under överföringen, vilket skyddar mot avlyssning och man-in-the-middle-attacker.
• venv/virtualenv: Dessa är verktyg för att skapa isolerade Python-miljöer. Att använda virtuella miljöer är avgörande för att hantera beroenden och undvika konflikter mellan olika projekt.

Konfigurera ditt projekt

Innan du kan distribuera ditt paket måste du strukturera ditt projekt korrekt.

Exempel på projektstruktur

my_package/
├── my_package/
│   ├── __init__.py
│   ├── module1.py
│   └── module2.py
├── tests/
│   ├── __init__.py
│   ├── test_module1.py
│   └── test_module2.py
├── README.md
├── LICENSE
├── setup.py
└── .gitignore

Förklaring:

• my_package/: Huvudkatalogen som innehåller ditt pakets källkod.
• my_package/__init__.py: Gör `my_package`-katalogen till ett Python-paket. Den kan vara tom eller innehålla initialiseringskod.
• my_package/module1.py, my_package/module2.py: Dina Python-moduler som innehåller den faktiska koden.
• tests/: En katalog som innehåller dina enhetstester. Det är avgörande att skriva tester för att säkerställa kvaliteten och tillförlitligheten hos ditt paket.
• README.md: En Markdown-fil som ger en beskrivning av ditt paket, användningsinstruktioner och annan relevant information. Detta är ofta det första användare ser på PyPI.
• LICENSE: En fil som innehåller licensen under vilken ditt paket distribueras (t.ex. MIT, Apache 2.0, GPL). Att välja en lämplig licens är avgörande för att specificera hur andra kan använda din kod.
• setup.py: Huvudkonfigurationsfilen som definierar ditt pakets metadata och bygginstruktioner.
• .gitignore: Specificerar filer och kataloger som ska ignoreras av Git (t.ex. temporära filer, byggartefakter).

Skapa `setup.py`-filen

`setup.py`-filen är hjärtat i din paketdistribution. Den innehåller metadata om ditt paket och instruktioner för att bygga och installera det. Här är ett exempel:

import setuptools

with open("README.md", "r") as fh:
    long_description = fh.read()

setuptools.setup(
    name="my_package",  # Ersätt med ditt paketnamn
    version="0.1.0",
    author="Your Name",  # Ersätt med ditt namn
    author_email="your.email@example.com", # Ersätt med din e-post
    description="Ett litet exempelpaket",
    long_description=long_description,
    long_description_content_type="text/markdown",
    url="https://github.com/yourusername/my_package", # Ersätt med URL till ditt repository
    packages=setuptools.find_packages(),
    classifiers=[
        "Programming Language :: Python :: 3",
        "License :: OSI Approved :: MIT License",
        "Operating System :: OS Independent",
    ],
    python_requires='>=3.6',
    install_requires=[
        "requests", # Exempelberoende
    ],
)

Förklaring:

• name: Namnet på ditt paket, som kommer att användas på PyPI. Välj ett unikt och beskrivande namn.
• version: Versionsnumret för ditt paket. Följ semantisk versionering (se nedan).
• author, author_email: Ditt namn och din e-postadress.
• description: En kort beskrivning av ditt paket.
• long_description: En längre, mer detaljerad beskrivning, vanligtvis läst från din `README.md`-fil.
• long_description_content_type: Specificerar formatet på din långa beskrivning (t.ex. "text/markdown").
• url: URL:en till ditt pakets hemsida (t.ex. GitHub-repository).
• packages: En lista över paket som ska inkluderas i din distribution. `setuptools.find_packages()` upptäcker automatiskt alla paket i ditt projekt.
• classifiers: Metadata som hjälper användare att hitta ditt paket på PyPI. Välj lämpliga klassificerare från listan över Trove Classifiers. Överväg att inkludera klassificerare för Python-versioner som stöds, operativsystem och licenser.
• python_requires: Specificerar den lägsta Python-version som krävs för att använda ditt paket.
• install_requires: En lista över beroenden som ditt paket kräver. Dessa beroenden installeras automatiskt när ditt paket installeras.

Versionshantering: Semantisk versionering

Semantisk versionering (SemVer) är ett allmänt vedertaget versionsschema som ger ett tydligt och konsekvent sätt att kommunicera arten av förändringar i ditt paket.

Ett SemVer-versionsnummer består av tre delar: MAJOR.MINOR.PATCH.

• MAJOR: Ökas när du gör inkompatibla API-ändringar. Detta indikerar en betydande förändring som kan kräva att användare uppdaterar sin kod.
• MINOR: Ökas när du lägger till funktionalitet på ett bakåtkompatibelt sätt. Detta signalerar nya funktioner eller förbättringar som inte bryter befintlig kod.
• PATCH: Ökas när du gör bakåtkompatibla buggfixar. Detta är för små fixar som inte lägger till nya funktioner eller bryter befintlig funktionalitet.

Exempel:

• 1.0.0: Första versionen.
• 1.1.0: Lade till en ny funktion utan att bryta befintlig kod.
• 1.0.1: Fixade en bugg i 1.0.0-versionen.
• 2.0.0: Gjorde inkompatibla API-ändringar.

Att använda SemVer hjälper användare att förstå effekten av att uppgradera till en ny version av ditt paket.

Bygga ditt paket

När du har konfigurerat din `setup.py`-fil kan du bygga ditt paket.

1. Skapa en virtuell miljö: Det rekommenderas starkt att skapa en virtuell miljö för att isolera ditt pakets beroenden. Använd `python3 -m venv .venv` (eller `virtualenv .venv`) och aktivera den sedan (`source .venv/bin/activate` på Linux/macOS, `.venv\Scripts\activate` på Windows).
2. Installera byggberoenden: Kör `pip install --upgrade setuptools wheel`.
3. Bygg paketet: Kör `python setup.py sdist bdist_wheel`. Detta kommando skapar två distributionsfiler i `dist`-katalogen: en källdistribution (sdist) och en wheel-distribution (bdist_wheel).

`sdist` innehåller din källkod och `setup.py`-fil. `bdist_wheel` är en förbyggd distribution som kan installeras snabbare.

Publicera ditt paket på PyPI

Innan du kan publicera ditt paket måste du skapa ett konto på PyPI (https://pypi.org/) och skapa en API-token. Denna token kommer att användas för att autentisera dina uppladdningar.

1. Registrera dig på PyPI: Gå till https://pypi.org/account/register/ och skapa ett konto.
2. Skapa en API-token: Gå till https://pypi.org/manage/account/, rulla ner till avsnittet "API tokens" och skapa en ny token. Förvara denna token säkert, eftersom du kommer att behöva den för att ladda upp ditt paket.
3. Installera Twine: Kör `pip install twine`.
4. Ladda upp ditt paket: Kör `twine upload dist/*`. Du kommer att bli ombedd att ange ditt användarnamn (__token__) och lösenord (den API-token du skapade).

Viktig säkerhetsanmärkning: Skicka aldrig in din API-token till ditt repository. Förvara den säkert och använd miljövariabler eller andra säkra metoder för att komma åt den under uppladdningsprocessen.

Testa installationen av ditt paket

Efter att ha publicerat ditt paket är det viktigt att testa att det kan installeras korrekt.

1. Skapa en ny virtuell miljö: Detta säkerställer att du testar installationen i en ren miljö.
2. Installera ditt paket: Kör `pip install ditt-paketnamn`.
3. Importera och använd ditt paket: I en Python-tolk, importera ditt paket och verifiera att det fungerar som förväntat.

Kontinuerlig integration och kontinuerlig leverans (CI/CD)

För att automatisera processen med att bygga, testa och publicera ditt paket kan du använda CI/CD-verktyg som GitHub Actions, GitLab CI eller Travis CI.

Här är ett exempel på ett GitHub Actions-arbetsflöde som bygger och publicerar ditt paket på PyPI:

name: Publicera på PyPI

on:
  release:
    types: [published]

jobs:
  publish:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v2
    - name: Konfigurera Python 3.x
      uses: actions/setup-python@v2
      with:
        python-version: 3.x
    - name: Installera beroenden
      run: |
        python -m pip install --upgrade pip
        pip install setuptools wheel twine
    - name: Bygg paket
      run: python setup.py sdist bdist_wheel
    - name: Publicera paket på PyPI
      run: |
        twine upload dist/* \
          -u __token__ \
          -p ${{ secrets.PYPI_API_TOKEN }}

Förklaring:

• Detta arbetsflöde utlöses när en ny release publiceras på GitHub.
• Det checkar ut koden, konfigurerar Python, installerar beroenden, bygger paketet och laddar upp det till PyPI.
• secrets.PYPI_API_TOKEN är en GitHub-hemlighet som lagrar din PyPI API-token. Du måste konfigurera denna hemlighet i inställningarna för ditt GitHub-repository.

Bästa praxis för distribution av Python-paket

• Skriv omfattande dokumentation: Inkludera en detaljerad `README.md`-fil, samt API-dokumentation med verktyg som Sphinx. Tydlig och komplett dokumentation är avgörande för att göra ditt paket lätt att använda.
• Skriv enhetstester: Testa din kod noggrant för att säkerställa dess kvalitet och tillförlitlighet. Använd ett testramverk som pytest eller unittest.
• Följ stilguiden PEP 8: Följ stilguiden i Python Enhancement Proposal 8 (PEP 8) för att säkerställa konsekvent och läsbar kod.
• Använd en licens: Välj en lämplig öppen källkod-licens för att specificera hur andra kan använda din kod.
• Håll dina beroenden uppdaterade: Uppdatera regelbundet ditt pakets beroenden för att dra nytta av buggfixar, säkerhetsuppdateringar och nya funktioner.
• Använd en virtuell miljö: Utveckla och testa alltid ditt paket i en virtuell miljö för att isolera beroenden.
• Överväg internationalisering (i18n) och lokalisering (l10n): Om ditt paket hanterar text eller data som visas för användaren, överväg att göra det anpassningsbart för olika språk och regioner. Detta utökar din potentiella användarbas globalt. Verktyg som Babel kan hjälpa till med detta.
• Hantera olika tidszoner och valutor: Om ditt paket hanterar datum, tider eller finansiella transaktioner, var medveten om olika tidszoner och valutor runt om i världen. Använd lämpliga bibliotek och API:er för att hantera dessa komplexiteter korrekt.
• Ge tydliga felmeddelanden: Skriv informativa felmeddelanden som hjälper användare att förstå vad som gick fel och hur man åtgärdar det. Översätt dessa felmeddelanden till olika språk om möjligt.
• Tänk på tillgänglighet: Ta hänsyn till användare med funktionsnedsättningar när du utformar ditt pakets gränssnitt och dokumentation. Följ riktlinjer för tillgänglighet för att säkerställa att ditt paket kan användas av alla.

Avancerade ämnen

• Namnrymdspaket (Namespace packages): Låter dig dela upp ett enda Python-paket över flera kataloger eller till och med flera distributioner.
• Ingångspunkter (Entry points): Låter dig definiera funktioner eller klasser som kan anropas från andra paket eller från kommandoraden.
• Datafiler: Låter dig inkludera filer som inte är Python-filer (t.ex. datafiler, konfigurationsfiler) i din distribution.
• Villkorliga beroenden: Låter dig specificera beroenden som endast krävs under vissa förhållanden (t.ex. på ett specifikt operativsystem).

Sammanfattning

Att distribuera ditt Python-paket på PyPI är ett utmärkt sätt att dela ditt arbete med världen och bidra till Pythons ekosystem. Genom att följa stegen och de bästa metoderna som beskrivs i den här guiden kan du skapa och publicera högkvalitativa Python-paket som är lätta att installera, använda och underhålla. Kom ihåg att prioritera tydlig dokumentation, noggranna tester och konsekvent versionshantering för att säkerställa framgången för ditt paket.